メインコンテンツまでスキップ

ファイルまたはディレクトリをコピー (file.copy)

宣言​

成否, エラー情報 = file.copy(コピー元パス, コピー先パス [, モード])

パラメータ​

  • コピー元パス
    文字列型。元のファイルまたはディレクトリの絶対パス
  • コピー先パス
    文字列型。コピー後のファイルまたはディレクトリの完全な絶対パス。対象のファイル名またはディレクトリ名を含みます
  • モード 20250914+
    文字列型のオプションパラメータ。コピーモード。指定できる値:
    • 空文字列または省略:デフォルトモード(no-clobber)。コピー先がすでに存在する場合は失敗を返します
    • "overwrite" または "o":上書きモード。既存のコピー先を直接置き換えます(既存のコピー先は削除されます)
    • "merge" または "m":マージモード(ディレクトリのみ)。コピー先にすでに存在するファイルを保持します
    • "overwrite-merge" または "om"/"mo":上書きマージモード。ディレクトリをマージし、同名のファイルを上書きします

戻り値​

  • 成否
    ブール型。操作に成功した場合は true、失敗した場合は false を返します
  • エラー情報
    文字列型。操作に失敗した場合のエラー情報

説明​

コピー元パス が指すファイルまたはディレクトリを、コピー先パス で指定した名前と場所にコピーします
この関数は「指定したパスをコピー先にする」操作であり、「指定したディレクトリの中にコピーする」操作ではありません。コピー先パス は最終的なファイルまたはディレクトリを指定し、元のファイル名やディレクトリ名は自動追加されません。コピー先がすでに存在するディレクトリである場合や、パスが / で終わる場合でも、そのディレクトリ内に元のファイルやディレクトリを配置することはありません
例えば、/a/b/c を名前 c のまま /d/e/ 内にコピーするには、コピー先パスを /d/e/c と指定する必要があります。/d/e/ だけではいけません
コピー先がすでに存在する場合は モード に従います。デフォルトモードでは失敗を返し、上書きモードではコピー先自体を置き換え、ディレクトリのマージモードでは元のディレクトリの内容をコピー先ディレクトリにマージします
キーワード:ファイルのコピー、ディレクトリのコピー、フォルダーのコピー
この関数は 20250313 以降のバージョンで使用できます

例​

ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('コピー失敗:'..err)
end

注記:上記のコードでは、この章で扱っていない関数 sys.alert を使用しています

別のディレクトリに名前を保持してコピーする​

-- /d/e は既存のディレクトリで、/d/e/c はまだ存在しないものとします
file.copy('/a/b/c', '/d/e/c') -- 正しい指定:c を /d/e/c としてコピーします

-- 誤った指定:対象は e 自体であり、e ディレクトリ内の c ではありません
file.copy('/a/b/c', '/d/e/') -- デフォルトモードでは対象がすでに存在するため失敗します

-- 上書きモードでは e 自体を置き換え、/d/e/c は作成しません(20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')

「ディレクトリ内にコピーする」関数の作成​

以下は独自のラッパー関数の例で、20250914 以降のバージョンが必要です。対象のディレクトリは存在している必要があります。この関数は元のファイル名またはディレクトリ名を保持し、省略可能な mode パラメータを file.copy に渡します。同名の項目がある場合も、指定したモードに従って処理します。

local function file_copy_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end

local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- 対象のディレクトリ自体やその親ディレクトリを最終的な対象にしないためのチェックです。
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end

local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.copy(src_path, dst_path, mode)
end

-- /d/e が既存のディレクトリであるとして、c を /d/e/c としてコピーします
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("コピー失敗:"..err)
end

-- /d/e/c を置き換えるには、呼び出し時に上書きモードを指定します:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")

注:上記のコードでは、file.exists、file.path.last_component、file.path.add_component を使用しています。